.TH std::getline 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::getline \- std::getline

.SH Synopsis
   Defined in header <string>
   template< class CharT, class Traits, class Allocator >

   std::basic_istream<CharT, Traits>&
       getline( std::basic_istream<CharT, Traits>& input,             \fB(1)\fP

                std::basic_string<CharT, Traits, Allocator>& str,
   CharT delim );
   template< class CharT, class Traits, class Allocator >

   std::basic_istream<CharT, Traits>&
       getline( std::basic_istream<CharT, Traits>&& input,            \fB(2)\fP \fI(since C++11)\fP

                std::basic_string<CharT, Traits, Allocator>& str,
   CharT delim );
   template< class CharT, class Traits, class Allocator >

   std::basic_istream<CharT, Traits>&                                 \fB(3)\fP
       getline( std::basic_istream<CharT, Traits>& input,

                std::basic_string<CharT, Traits, Allocator>& str );
   template< class CharT, class Traits, class Allocator >

   std::basic_istream<CharT, Traits>&                                 \fB(4)\fP \fI(since C++11)\fP
       getline( std::basic_istream<CharT, Traits>&& input,

                std::basic_string<CharT, Traits, Allocator>& str );

   getline reads characters from an input stream and places them into a string:

   1,2) Behaves as UnformattedInputFunction, except that input.gcount() is not
   affected. After constructing and checking the sentry object, performs the following:
   1) Calls str.erase().
   2) Extracts characters from input and appends them to str until one of the following
   occurs (checked in the order listed)
   a) end-of-file condition on input, in which case, getline sets eofbit.
   b) the next available input character is delim, as tested by Traits::eq(c, delim),
   in which case the delimiter character is extracted from input, but is not appended
   to str.
   c) str.max_size() characters have been stored, in which case getline sets failbit
   and returns.
   3) If no characters were extracted for whatever reason (not even the discarded
   delimiter), getline sets failbit and returns.
   3,4) Same as getline(input, str, input.widen('\\n')), that is, the default delimiter
   is the endline character.

.SH Parameters

   input - the stream to get data from
   str   - the string to put the data into
   delim - the delimiter character

.SH Return value

   input

.SH Notes

   When consuming whitespace-delimited input (e.g. int n; std::cin >> n;) any
   whitespace that follows, including a newline character, will be left on the input
   stream. Then when switching to line-oriented input, the first line retrieved with
   getline will be just that whitespace. In the likely case that this is unwanted
   behaviour, possible solutions include:

     * An explicit extraneous initial call to getline.
     * Removing consecutive whitespace with std::cin >> std::ws.
     * Ignoring all leftover characters on the line of input with
       cin.ignore(std::numeric_limits<std::streamsize>::max(), '\\n');.

.SH Example

   The following example demonstrates how to use the getline function to read user
   input, and to process a stream line by line, or by parts of a line using the delim
   parameter.


// Run this code

 #include <iostream>
 #include <sstream>
 #include <string>

 int main()
 {
     // greet the user
     std::string name;
     std::cout << "What is your name? ";
     std::getline(std::cin, name);
     std::cout << "Hello " << name << ", nice to meet you.\\n";

     // read file line by line
     std::istringstream input;
     input.str("1\\n2\\n3\\n4\\n5\\n6\\n7\\n");
     int sum = 0;
     for (std::string line; std::getline(input, line);)
         sum += std::stoi(line);
     std::cout << "\\nThe sum is " << sum << ".\\n\\n";

     // use separator to read parts of the line
     std::istringstream input2;
     input2.str("a;b;c;d");
     for (std::string line; std::getline(input2, line, ';');)
         std::cout << line << '\\n';
 }

.SH Possible output:

 What is your name? John Q. Public
 Hello John Q. Public, nice to meet you.

 The sum is 28.

 a
 b
 c
 d

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR   Applied to          Behavior as published               Correct behavior
   LWG 91 C++98      getline did not behave as an unformatted behaves as an unformatted
                     input function                           input function

.SH See also

   getline extracts characters until the given character is found
           \fI(public member function of std::basic_istream<CharT,Traits>)\fP
